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Class RWsSession 



RWsSession 



Support 

Supported from 5.0 

Description 

Window server session. 

The session between the client and the window server can be used to mediate asynchronous events, and for client interface 
control and system control. A description of each of these capabilities is given below. 

This class is not intended for user derivation. 

Mediating asynchronous events: 

Primarily, the session mediates asynchronous events to the user. Three event streams are available: the standard event stream 
which all applications must use; the redraw event stream which must be used by all applications except those which exclusively use 
backed-up windows; and the priority key event stream which may be used for abort keys and the like for specialist applications. 

All these events are mediated as standard asynchronous services. Typical window server client programs encapsulate each 
service they require in an active object whose RunLO identifies the event and calls the appropriate member function of a class 
associated with an application framework, or a window. 

Client interface control: 

The client's interface with the window server has several aspects, each of which is controlled through the window server session. 
• Flushing defines how requests to the window server are handled. 



Many system-wide settings may be controlled by any application through its window server session. Typically, these functions are 
only used by the system shell and its associated sessions/applications. 

• Auto-repeat and double-click. 

• Query all window groups in the system. 

• Setting the default shadow vector 

• Setting the system pointer cursors 

• Counting resources used by the window server. This is only useful for debugging checks. 

• Getting and checking the state of the modifier keys (SHIFT, CTRL AND FN) 

• Setting the window server background colour 
Derivation 

Misciierjici^ss Base class for all classes whose objects are clients of the window server engine 



System control: 
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A handle to an object 



Client-side handle to a session with a server 



RWsSession 



Window server session 
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Construction and destruction 



on ( ) 



RWsSession () ; 

Descriptor* 

Default C++ constructor. 

Constructs an uninitialised window server session. Note that it does not establish a connection to the window server — this must 
be done explicitly by calling the session's connect o function. Before connect o is called, no corresponding session object exists in 
the server, and the RWsSession contains no meaningful handle. 



Connect () 

Tint Connect () ; 

Descriptors 

Connects the client session to the window server. 

connect o should be the first function called on an RWsSession object after it is created. The function establishes a connection to 
the window server, creating a corresponding session object in the server. Each session has one and only one connection to the 
server — attempting to call connect o when a connection has already been made will cause a panic. 

After a connection has been successfully established, all events are delivered to the client application through the RWsSession 
object. 

Return vafitse 



Tint KErrNone if successful, otherwise another of the system-wide error codes. 



Close { ) 

void Close () ; 
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Closes the window server session. 

This function cleans up all resources in the RWsSession and disconnects it from the server. Prior to disconnecting from the window 
server the client-side window server buffer is destroyed without being flushed. This function should be called when the RWsSession 
is no longer needed — normally just before it is destroyed. 

Version { ) 

TVersion Version (); 

DescrSpijori 

Gets the window server version. 
Rsfcurrc value 

wersion Window server version containing major and minor version numbers, and build version. 

Member functions 



C I a i y s fcefftP © i n fce rCu r s o r L i s "t ( ) 

Tint ClaimSystemPointerCursorList () ; 

Description 

Claims the system pointer cursor list. A client must call this function before it can call SetSystemPointerCursor () or 

ClearSystemPointerCursor () . 

Tint KErrNone if successful, KErrinUse if another client is already using the system pointer cursor list, otherwise another of the 
system-wide error codes. 

See aiso: 

CiearDefaultSystemPointerCurscr ( ) 

void Clear DefaultSystemPointer Cursor () ; 

Support 

Supported from 6.0 
Description 

Clears the default system pointer cursor. 

This sets the pointer to the current default system pointer cursor to NULL. 
Panne codes 

42 If this function is called by a client other than the owner of the system pointer cursor list. 

Clear Ho fcKeys {) 

Tint ClearHotKeys (THotKey aType) ; 
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Description 

Clears all mappings for the specified hotkey, including the default mapping. 

Hotkeys allow standard functions to be performed by application-defined key combinations. 

Parameters 

THotKey aType The hot key to be cleared 

Tint KErrNone if successful, otherwise one of the system-wide error codes. 
See also; 

• P^storeOetauILHotXey {) 



ClearSystemPointerCursor { ) 

void ClearSystemPointerCursor (Tint aCursorNumber); 

Descriptor* 

Clears a system pointer cursor from the list. 

Before calling this function, the client must first gain access to the list by calling ciaimSystemPointerCursorList o . 
Parameters 

Tint aCursorNumber Cursor number to clear 

CoirtputeMode { ) 

void ComputeMode (TComputeMode aMode) ; 

Description 

Sets the mode used to control process priorities. 

The default window server behaviour is that the application that owns the window with keyboard focus gets foreground process 
priority (EPriorityForeground) while all other clients get background priority (EPriorityBackground). This function can be used to 
over-ride this default behaviour, as discussed in TComputeMode. 

Note: 

• Unlike real Symbian devices, the Emulator runs on a single process. As a result, on the Emulator this function sets the 
priority of individual threads rather than of processes. The values used for thread priorities are EPriorityLess instead of 

EPriorityBackground, and EPriorityNormal instead Of EPriorityForeground. 

Parameters 

TComputeMode aMode The Compute mode. 

EventReady ( ) 

void EventReady (TRequest Status* aStat) ; 

Description 

Requests standard events from the window server. 

Standard events include all events except redraws and priority key events. 

The client application will typically handle the completed request using the RunLO function of an active object, and in this case the 
request status astat should be the istatus member of that CActive object. 

Note: 
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• The active object runs when an event is waiting — you should call GetEvento in the RunLO function to get the event. 

• You should not call this function again until you've either called GetEvento or EventReadyCancei ( ) 
Parameters 

TRequest status* Request status. On successful completion contains KErrNone, otherwise another of the system-wide 

aStat error codes. 

See aJso: 



CActive 



EventReadyCancei f) 

void EventReadyCancei ( ) ; 

Description 

Cancels a request for standard events from the window server. This request was made using EventReadyO . 

The client application will typically use an active object to handle standard events, and this function should be called from the 
active object's DoCancei o function. 

See a^so: 

FindWindowGroupIdentif ier ( ) 

Tint FindWindowGroupIdentif ier (Tint aPreviousIdentifier, const TDesC& aMatch, Tint aOffset=0) ; 

Description 

Gets all window groups whose names match a given string — which can contain wildcards. 

An example use of this function might be in order to find all the currently running copies of a particular application, assuming that 
the window group name contained the application name. An optional argument, aotf set, specifies the number of characters to be 
ignored at the beginning of the window group name. As several window group names may match the given string, and the function 
can return only one at a time, there is an argument, aPreviousidentif ier, which gives the identifier for the previous match that 
was returned. In other words, it means, "get me the next match after this one." The first time the function is called, give 0 as the 
previous identifier. 

Matching is done using TDesC: :MatchF(), which does a folded match. Wildcards '*' and '?' can be used to denote one or more 
characters and exactly one character, respectively. Windows are searched in front to back order. 

Parameters 

TInt Identifier of the last window group returned. If the value passed is not a valid identifier, the function 

aPreviousIdentifier returns KErrNotFound. 

const TDesc& aMatch String to match window group name against: may contain wildcards 

Tint aOffset=o The first aotfset characters of the window group name are ignored when doing the match. 

Return value 

Tint The next window group, after the one identified by aPreviousIdentifier, whose name matches aMatch. KErrNotFound if 
no window group matched or aPreviousIdentifier was not a valid identifier. 

FindvfindowGr oupldeni-.ifier { ) 

Tint FindWindowGroupIdentif ier (Tint aPreviousIdentifier, TThreadld aThreadld) ; 

Description 

Gets the identifiers of window groups belonging to a client which is owned by a thread with the specified thread ID. 
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The thread may own more than one window group, so the identifier returned is the one after aPreviousidentifier. The first time 
the function is called, use 0 for the previous identifier. 

Parameters 

Tint aPreviousidentifier identifier returned by previous call 
TThreadid aThreadid Thread owning the window group or groups. 

Return vaSue 

Tint Next window group identifier after the one identified by aPreviousidentifier 
Flush ( ) 

void Flush () ; 

Description 

Sends all pending commands in the buffer to the window server. 

Delivering a command to the window server requires a context switch, and so it is more efficient to deliver several commands in 
one go. Hence all client commands are normally first placed into a buffer for delivery to the window server. 

The buffer is delivered when: 

• It gets full. 

• A command that returns a value is called (there are a few exceptions to this). 

• This function is called. 
Note: 

• This function is called when a prompt response is required from the window server, e.g. after doing some drawing. 

FreeSystemPcinterCurscrList ( ) 

void FreeSystemPointerCursorList ( ) ; 

Description 

Releases the system pointer cursor list and deletes all the entries in it. 

A client should call this function when it no longer needs the system pointer cursor list. 

GetBackgroundColor ( ) 

TRgb GetBackgroundColor () const; 

Description 

Gets the window server background colour. 
Return va@ue 

TRgb Background colour 

GetCoIorModeList ( ) 

Tint GetColorModeList (CArrayFixFlat<TInt> *aModeList) const; 

Desera pliers 

Gets the list of available colour modes. 
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Note: 

• This function should usually be called within user: :LeaveifError o . 

• The only time that an error can be generated is when the array gets resized to the number of display modes. Thus if you 
make the size of your array equal to the maximum number of display modes over all hardware then this function will never 
leave. Currently there can only ever be 1 1 as that is the number of different values in TDispiayMode. 

• This function was not const prior to version 6.0. 
Parameters 

CArrayFixFiat<Tint> * On return, contains a TDispiayMode entry for each of the available display modes. Note that the 

aModeList array's contents are deleted prior to filling with display mode information. 

Tint KErrNone if successful. KErrNoMemory if aModeList must be re-sized to hold all the display modes and this results in an 
OOM error. 

GetJjftf aultOwningWindow ( ) 

Tint GetDefaultOwningWindow () ; 

Gets the identifier of the current default owning window group. 
Refcurn value 

Tint identifier of current default owning window group. Returns 0 if there isn't one. 

TDispiayMode GetDefModeMaxNumColors (Tints aColor,TInt& aGray) const; 

Description 

Gets the number of colours available in richest supported colour mode, the number of greys available in the richest grey mode, 
and returns the default display mode. 

Note: 

• This function was not const prior to version 6.0. 
Parameters 

Tints acoior The number of colours in the richest supported colour mode. 
Tints aGray The number of greys in the richest supported grey mode. 

Refcuro value 

TDispiayMode The default display mode. 

GetDoiifoleClickSet*fclngs {) 

void GetDoubleClickSettings (TTimeIntervalMicroSeconds32 Salnterval, Tint &aDistance) ; 

Description 

Gets the current system-wide settings for pointer double clicks. 
Note: 

• Double click distances are measured in pixels as the sum of the X distance moved and the Y distance moved between 
clicks. For example: a first click at 10, 20 and a second click at 13,19 gives a distance of (1 3-10)+(21-20) = 4. 

Parameters 
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TTimeintervaiMicroSeconds32& aintervai Maximum interval between clicks that constitutes a double click 
Tint &aDistance Maximum distance between clicks that constitutes a double click 

See alsoi 

GetEvent f ) 

void GetEvent (TWsEvent & aEvent); 

Descriptor* 

Gets a standard event from the session for processing. 

The type of event returned by GetEvent o may be any of those listed in TEventcode. To access the data within an event, the event 
should be converted to the appropriate type, using functions provided by the TWsEvent class — TWsEvent also provides a function 
to find out the type of the event. 

Note: 

• It is possible that the returned event is of type EEventNuii. Clients should normally ignore these events. 

• This function should only be called in response to notification that an event has occurred — otherwise the client will be 
panicked. 

This function would normally be called in the RunLO function of an active object which completes with the EventReadyO 
function's request status. 

Parameters 

TWsEvent & aEvent On return, contains the event that occurred 
See also: 

GetFocusWindowGroup ( ) 

Tint GetFocusWindowGroup () ; 

Descriptors 

Gets the identifier of the window group that currently has the keyboard focus. 
Note: 

• This might not necessarily be the front-most window group, as window groups can disabled keyboard focus. 
Return vafiue 

TInt Identifier of window group with keyboard focus. 

GetKeyboardRepeatKate ( ) 

void GetKeyboardRepeatRate (TTimeIntervalMicroSeconds32 & alnitialTime, TTimeIntervalMicroSeconds32 & aTime) ; 

Descriptor* 

Gets the current system-wide settings for the keyboard repeat rate. 
Parameters 
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TT±meintervaiMicroSeconds32& ainitiaiTime Time before first repeat key event 
TTimeintervaiMicroSeconds32& aTime Time between subsequent repeat key events 

See also: 



GetModi fie r State {) 



Tint GetModifierState () const; 



Descjfspfciem 

Get the state of modifier keys. 

The state of each modifier key (defined in TEventModifier) is returned in a bitmask. 



The modifier keys are: EModifierLeftAlt, EModi fier Right Alt, EModifierAlt, EModifierLeftCtrl, EModif ierRightCtrl, 
EModifierCtrl, EModif ierLef tShif t, EModif ierRight Shift, EModif ierShift, EModif ierLeftFunc, EModif ierRightFunc, 
EModif ier Fun c, EModif ierCapsLock, EModif ierNumLock, EModif ierScrollLock, , , , 



Return vaSuss 



Tint Modifier state 



See aSso; 



GetPriorityKey ( ) 

void GetPriorityKey (TWsPriorityKeyEvent & aEvent); 

Description 

Gets the completed priority key event from the window server session. 

Priority key events are typically used for providing "Abort" or "Escape" keys for an application. 

This function is similar to GetEvento , except that it returns a TWsPriorityKeyEvent instead of a TWsEvent. 

Note: 

• This should only be called after notification that a priority key event has occurred. 
Parameters 

TWsPriorityKeyEvent& aEvent On return, contains the priority key event that occurred. 
See aSso; 



GetRedraw { ) 

void GetRedraw ( TWsRedrawEvent & aEvent); 

Description 

Gets the redraw event from the session. 

This function is similar to GetEvento , except that the event is returned as a TWsRedrawEvent, and hence there is no need to convert 

it from a TWsEvent. 

The function should only be called after notification that a redraw is waiting. 
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Parameters 

TWsRedrawEvent& aEvent On return, contains the redraw event that occurred 
See aSso: 



GetWindowGroupClientThreadXd f ) 

Tint GetWindowGroupClientThreadId(TInt aidentifier, TThreadld SaThreadld) ; 

Description 

Gets the thread ID of the client that owns the window group specified by the window group identifier. 

Parameters 

Tint aidentifier The window group identifier 

TThreadid &aThreadid On return, contains the thread ID 

Return v&hm 

Tint KErrNone if successful, otherwise another of the system-wide error codes. 

GetWindcwGzcupHandle {) 

Tint GetWindowGroupHandle (Tint aidentifier); 

Descriptor* 

Gets the handle of the window specified by the window group identifier. 

This is the handle that was passed as an argument to RwindowGroup: : Construct o . 

Parameters 

Tint aidentifier The window group identifier 

Return vafiue 

Tint Handle of the window group 

Tint GetWindowGroupNameFromldentif ier (Tint aidentifier, TDes& aWindowName); 

Description 

Gets the name of a window group from its identifier. 

Using the list of identifiers returned by windowGroupList o , it is possible to get the names of all window groups in the system. Note 
that window names are a zero length string by default. 

Note: 

• Note that the window group name must have been previously set using RwindowGroup: :SetName() to contain a meaningful 
value. 

Parameters 

Tint aidentifier The identifier of the window group whose name is to be inquired 
TDes & aWindowName On return, contains the window group name 
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Return vafiue 

TInt KErrNone if successful, otherwise another of the system-wide error codes 

GatWindowGroupOrdinalPriorl-ky ( ) 

Tint GetWindowGroupOrdinalPriority (Tint aldentif ier) ; 

DescifBpticm 

Gets a window group's priority. 
Parameters 

Tint aidentif ier The window group identifier 

Return vaSue 

Tint The window group priority 

HeapCount ( ) 

Tint HeapCount () const; 

Description 
Gets the heap count. 

This function calls RHeap: : count o on the window server's heap, after throwing away all the temporary objects allocated for each 
window. 

Return vaBue 
Tint The window server's heap count. 

HeapSetFail () 

void HeapSetFail (RHeap : :TAllocFail aType,TInt aValue) ; 

Description 

Sets the heap failure mode in the window server. 

The release version of the base does not support simulated heap failure functionality, and the result of this function is additional 
error messages. In the debug version the clients are notified of the simulated failure and handle it. 

See RHeap: : DbgSetAiiocFaii ( ) for more information. 

Note: 

• It is unlikely, but possible to create a ROM with a mixture of Release and Debug versions of the Base and Window Server 
DLLs, which results in different behaviour to that described above. If you run a debug Window Server with a release version 
of the Base, then calling this function will result in neither extra error messages (e.g. EDrawingRegion) nor simulated heap 
failures. However if you have a release Window Server with a debug Base then you will get both simulated heap failures and 
the extra error messages. 

Parameters 

RHeap: :TAiiocFaii aType An enumeration which indicates how to simulate heap allocation failure. 

Tint aValue The rate of failure; when aType is RHeap: :EDeterministic, heap allocation fails every aRate attempt 

See aiso; 
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LogCommand { ) 
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void LogCoramand (TLoggingCornmand aCommand) ; 

Support 

Supported from 7.0 

Descriptors 

Allows the window server client to enable or disable logging of window server events. 

The type of logging that takes place (e.g. whether to file or to serial port) depends on the settings specified in the wsini.ini file. 
Clients can also force a dump of the window tree or information about the window server's heap size and usage. 
Parameters 

IJ^^k^Q^Qr^and aCommand The logging command. 

• For logging to work, the wsini.ini file has to specify the type of logging required and the DLLs for that type of logging must 
have been correctly installed. Otherwise, calling this function will have no effect. 

See also: 

LogMessage { ) 

void LogMessage (const TLogMessageText SaMessage) ; 

Descriptors 

Adds a message to the window server debug log if one is currently in operation. 
Parameters 

const TLogMessageText& aMessage The text added to the message log. 

NumWindowGroups {) 

Tint NumWindowGroups ( ) const; 

Gets the total number of window groups currently running in the window server. 
This includes all the groups running in all sessions. 
Return vafiue 

Tint Total number of window groups running in the server 

Tint NumWindowGroups (Tint aPriority) const; 

Description 

Gets the number of window groups of a given window group priority running in all sessions in the window server. 
Parameters 

Tint apriority Window group priority 
Return vaSue 
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Tint Number of window groups of priority apriority 



PasswordEntered { ) 

void PasswordEntered () ; 

Description 

Disables window server password mode. 

This function must be called by the session which owns the password window when the correct machine password has been 
entered. 



Pointer Curs or Are a ( ) 

TRect PointerCursorArea () const; 

Supported from 6.0 
Description 

Gets the pointer cursor area for the first screen display mode. 

This is the area of the screen in which the virtual cursor can be used while in relative mouse mode. While in pen or mouse mode 
the event co-ordinates are forced to be within this area unless you click outside the drawable area. 

Return vaBue 

TRect The pointer cursor area for the first screen display mode. 
See aSso: 

_ Set P o i lit s- . r O u r s , o r Ar e a i ) _ 



PointerCursorArea { ) 

TRect PointerCursorArea (Tint aScreenSizeMode) const; 

Support 

Supported from 6.0 

Gets the pointer cursor area for the specified screen display mode. 

This is the area of the screen in which the virtual cursor can be used while in relative mouse mode. While in pen or mouse mode 
the event co-ordinates are forced to be within this area unless you click outside the drawable area. 

Parameters 

Tint aScreenSizeMode The screen mode for which the pointer cursor area is required. 
Reta.srn vaBus 

TRect The pointer cursor area for the specified screen display mode. 
See aSso; 

Pointer Cur sorMode {) 
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TPointerCursorMode PointerCursorMode ( ) const; 

Support 

Supported from 6.0 
Description 

Gets the current mode for the pointer cursor. 

The mode determines which sprite is used for the pointer cursor at any point. 

Return value 

TPointerCursorMode The current mode for the pointer cursor. 



PointerCursorPcsition { ) 

TPoint PointerCursor Position () const; 

Support 

Supported from 6.0 

Description 

Gets the pointer cursor position. 

This function allows an application to determine the position of the virtual cursor. 
Return vaBue 

TPoint The position of the virtual cursor. 

PurgeFoin terEven fcs ( ) 

void PurgePointerEvents () ; 

Description 

Removes all pointer events waiting to be delivered to this session. 

The events are removed from the event queue without being processed. This might occur, for example, at application startup. 



PriorifcyKeyReady ( ) 

void Prior ityKeyReady (TRequestStatus *aStat) ; 

Description 

Requests priority key events from the window server. 

Typically, an client will create an active object for priority key events with a higher priority than the active objects for standard 
events. The client will then normally handle completed priority key requests in the active object's RunLO function. 

As in EventReady o , the request status argument should be the set to the istatus member of CActive. When priority key events 
occur, they are obtained using GetPriorityKey o . 

Note: 

• YOU Should not call this function again until you've either called GetPriorityKey () or PriorityKeyReadyCancel () . 

Parameters 

TRequeststatus* Request status. On successful completion contains KErrNone, otherwise another of the system-wide 

aStat error codes. 

See also: 



http://www.symbian.com/developer/techlib/v70 



Page 14 of 28 



RWsSession in Window Server 



10/1/05 3:04 pm 



m ^Ct-iyie 



PriorityKeyReadyCancel {) 

void Priori tyKeyReadyCancel () ; 

Description 

Cancels a priority key event request. 

If active objects are used, this function should be called from the active object's DoCanceio function. 
See also: 

• FriorJ.tyKevPeady^ 

Redr&wReady ( ) 

void RedrawReady (TRequest Status* aStat) ; 

Description 

Requests redraw events from the window server. 

Typically, a client will create an active object for redraw events with a lower priority than the active objects for standard events. The 
client will then typically handle completed redraw requests in the active object's RunLO function. 

As in EventReady o , the request status astat should be used as the istatus member of an active object. When a redraw event 
occurs the active object's RunLO function is called — the redraw event can be obtained by calling GetRedrawO in the RunL ( ) . 

Note: 

• You should not call this function again until you've either called GetRedrawO or RedrawReadyCancei o . 
Parameters 

TRequeststatus* The request status. On successful completion contains KErrNone, otherwise another of the system-wide 

aStat error codes. 

See aSso; 

• ££^gdrawXL 



RedrawReadyCancei () 

void RedrawReadyCancei () ; 

Description 

Cancels a redraw event request. 

If active objects are used, this function should be called from the active object's DoCanceio function. 

See also: 

RequestiOff Events {) 

Tint RequestOffEvents (TBool aOn, RWindowTreeNode* aWin=NULL) ; 

Support 
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Supported from 6.0 
Description 

Requests the window server to send OFF events to a window. 



This replaces sendoff Event :sto she li window () in versions prior to 6.0. 



This function is called by a client to command the window server to send it OFF events. The window server then sends the window 
OFF events when an action occurs which requires power down, rather than handling powering down itself. 



Notes: 



• Any client can ask for OFF events, but only one window in the system can be set to receive them. If this function is called 
when another window is set to receive OFF events then the client will be panicked. The exception is the shell, which is 
allowed to take receipt of OFF events from other clients. 

• The window server identifies the shell client by comparing the process name of the client with the process name of the shell. 
Only the first client created by the shell is guaranteed to have the extra shell client privileges. 

• Prior to ER4, the window server handled all powering down. However since powering down is policy dependent it can be 
handled by the shell. 

• This function does not automatically flush the client side buffer, and hence does not become active until the buffer is 
flushed. The shell should arrange for a function that does flush the buffer to be called soon afterwards. See Flush o . 

• If the shell dies or terminates just before the action requiring power down happens then the window server will handle it 
rather than passing it on to the shell. 

• The window server has a queue of messages that it is waiting to send to clients. If the shell's client's queue is full and the 
window server cannot make room for the OFF message then it will power down the machine itself. 



Parameters 



tbooi aon ETrue to get the window server to send EEventsheiiswitchOff messages to the shell (rather than powering 

down). EFaise makes the window server switch back to powering down the machine itself. 

RwindowTreeNode * The handle to the window or window group of the shell — to which the message is to be sent. This may 
awin=NULL NULL only if aOn=EFaise, i.e. the window server is handling power down itself. If aOn=ETrue then this 

must not be NULL, or the Window Server will panic the shell. Note that as far as the window server is 

concerned the handle must exist when this function is called. 



Refcurrc value 



TInt KErrNone if successful, otherwise another of the system-wide error codes. 



Panic codes 



si If this function is called when a window has already been set to receive OFF events. The exception is the shell, which may 
take the receipt of OFF events away from other windows. 



ResourceCount { ) 

Tint ResourceCount ( ) ; 

Description 

Gets the number of objects that the server has allocated for that client. 

This function can be used to check that the client has correctly cleaned up all of its objects. 

Return vaBue 

Tint The number of resources allocated to the client. 



RestoreDef aultHotKey ( ) 

Tint RestoreDef aultHotKey (THotKey aType) ; 

Description 

Restores the default mapping for a hot key. 
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The function clears current mappings for a hot key and restores the default mapping 

Parameters 

THotKey aType The hot key to restore to its default value 
Return vaBue 

TInt KErrNone if successful, otherwise another of the system-wide error codes. 
See also: 

• ClearHot^vslL 

S e> vi dE n t T oA 1 IWlndowGr oup s ( ) 

Tint SendEventToAllWindowGroups (const TWsEvent& aEvent) ; 

Support 

Supported from 5.1 
Description 

Sends the specified event to all existing window groups. 

Parameters 

const TWsEvent& aEvent The event to be sent to all window groups. 
Return valuB 

Tint KErrNone if successful, otherwise another of the system-wide error codes. 

SendEventToAllWindowGroups ( ) 

Tint SendEventToAllWindowGroups (Tint aPriority, const TWsEventS aEvent) ; 

Support 

Supported from 5.1 
Description 

Sends the specified event to all window groups with the specified priority. 
Parameters 

Tint apriority The priority which window groups must have to be sent the message, 

const TWsEvent& aEvent The event to be sent to the specified window groups. 

Return vaflue 

Tint KErrNone if successful, otherwise another of the system-wide error codes. 

SendEYentSciindowGroup ( ) 

Tint SendEventToWindowGroup (Tint aldentifier, const TWsEvent& aEvent); 

Description 

Sends an event to a window group. 

Para meters 
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— see THotKey for the default. 
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Tint aidentifier Window group identifier 

const TWsEvent& aEvent Event to send to window group 

Return v&\u& 

Tint KErrNone if successful, otherwise another of the system-wide error codes. 

SendMessageToAllStfindowGroups { ) 

Tint SendMessageToAllWindowGroups (TUid aUid, const TDesC8& aParams) ; 

Support 

Supported from 6.0 
Description 

Sends a message to all window groups. 
Note: 

• In order to receive messages sent using this function you will need to implement the MCoeMessageOb server interface which is 
defined in the Ul Control Framework API. 

Parameters 

TUid auid A UID which uniquely identifies the session sending the message. 

const TDesC8& aParams The message data. An unlimited amount of data can be passed in this argument. 

Return valuQ 

Tint KErrNone if successful, otherwise another of the system-wide error codes. 

SendMessageToAllWindowGroups O 

Tint SendMessageToAllWindowGroups (Tint aPriority, TUid aUid, const TDesC8& aParams); 

Support 

Supported from 6.0 

Sends a message to all window groups with the specified priority. 
Note: 

• In order to receive messages sent using this function you will need to implement the MCoeMessageOb server interface which is 
defined in the Ul Control Framework API. 

Parameters 

Tint apriority The priority which window groups must have to be sent the message. 

TUid auid A UID which uniquely identifies the session sending the message. 

const TDesC8& aParams The message data. An unlimited amount of data can be passed in this argument. 

Return vafiue 

Tint KErrNone if successful, otherwise another of the system-wide error codes. 

SendMe s s age 5 oiindowGr oup ( ) 

Tint SendMessageToWindowGroup (Tint aidentifier, TUid aUid, const TDesC8& aParams); 
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Description 

Sends a message to a window group. 

The window group will then receive an event of type EEventMessageReady notifying it that a message has been received. The 
window group can belong to this or another session. 

Pre version 6.0: 

Prior to version 6.0 the message can then be retrieved using RwindowGroup : : FetchMessage o . 

An application must ensure that it calls RwindowGroup : : FetchMessage o whenever it receives an EEventMessageReady event. It will 
receive no further EEventMessageReady events until it does so. However application developers using the standard GUI framework 

Should note that CEikAppUi Calls RwindowGroup: : FetchMessage () automatically. 

Version 6.0 and onward: 

From version 6.0 RwindowGroup: :FetchMessage o has been removed. In order to receive messages sent using this function you will 
need to implement the MCoeMessageObserver interface which is defined in the Ul Control Framework API. 

Parameters 

Tint aidentif ier The identifier of the window group to receive the message. 

Tuid auid A UID which uniquely identifies the session sending the message. 

const TDesC8& aParams The message data. An unlimited amount of data can be passed in this argument. 

Tint KErrNone if successful, otherwise another of the system-wide error codes. 
See also: 



SendOf f Event sToShell Window ( ) 

void SendOff Event sToShellWindow (TBool aOn,RWindowTreeNode *aWin=NULL) ; 

Withdrawn in 6.0 

Description 

Requests the window server to send OFF events to the shell window. 

This function is called by the shell to command the window server to send it OFF events. The window server then sends the shell 
OFF events when an action occurs which requires power down, rather than handling powering down itself. 

Notes: 

• Prior to ER4, the window server handled all powering down. However since powering down is policy dependent it can be 
handled by the shell. 

• The window server identifies the shell client by comparing the process name of the client with the process name of the shell. 
Only the first client created by the shell is guaranteed to have the extra shell client privileges. 

• This function does not automatically flush the client side buffer, and hence does not become active until the buffer is 
flushed. The shell should arrange for a function that does flush the buffer to be called soon afterwards. See Flush o . 

• If the shell dies or terminates just before the action requiring power down happens then the window server will handle it 
rather than passing it on to the shell. 

• The window server has a queue of messages that it is waiting to send to clients. If the shell's client's queue is full and the 
window server cannot make room for the OFF message then it will power down the machine itself. 

• In version 6.0 this function is replaced by: 

Tint RequestOff Events (TBool aOn, RWindowTreeNode *aWin=NULL) ; 

Parameters 
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tbooi aOn ETrue to get the window server to send EEventsheiiswitchOf f messages to the shell (rather than powering 

down). EFaise makes the window server switch back to powering down the machine itself. 

RwindowTreeNode * The handle to the window or window group of the shell — to which the message is to be sent. This may 
awin=NULL b e NULL only if aOn=EFaise, i.e. the window server is handling power down itself. If aOn=ETrue then this 

must not be NULL, or the Window Server will panic the shell. Note that as far as the window server is 
concerned the handle must exist when this function is called. 

SetAutoFlush { ) 

TBool SetAutoFlush (TBool aState) ; 

Sets a session's auto-flush state. 

If auto-flush is set to ETrue, the window server buffer is flushed immediately anything is put into it, instead of waiting until it 
becomes full. This setting is normally used only in a debugging environment. 

If the auto-flush state is EFaise, the window server buffer is flushed normally. 

Parameters 

tbooi astate E True to set auto-flushing on, EFaise to disable auto-flushing. 
Return value 
tbooi Previous auto-flush state 

SetB&ckgroundColcr ( ) 

void SetBackgroundColor (TRgb aColor) ; 

Description 

Sets the background colour for the window server. 

This background can only be seen in areas of the display that have no windows on them: so for many applications it will never be 
seen — it affects no other windows. 

Parameters 
TRgb acoior Background colour 

SetDefaultFadingParajneters ( ) 

void SetDefaultFadingParameters (TUint8 aBlackMap, TUint8 aWhiteMap) ; 

Support 

Supported from 6.0 
Description 

Sets the default fading parameters. 

Fading is used to change the colour of a window to make other windows stand out. For example, you would fade all other 
windows when displaying a dialogue. This function sets whether, and the amount by which, fading makes a faded window closer to 
white or closer to black. 

Fading re-maps colours in the faded window to fall between the specified black and white map values. If aBiackMap=o and 
awhiteMa P =255 then the colours are mapped unchanged. As the values converge the colours are mapped to a smaller range — so 
the differences between colours in the faded window decrease. If the values are reversed then the colours are inverted (i.e. where 
the unfade window would be black, it is now white). 

Changing the default will automatically apply to current graphic contexts but will not have any affect on windows that are already 
faded. 

Note: 
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• RwindowTreeNode: :SetFaded() and cwindowGc : : setFaded ( ) use these fading parameters, and allow control over the exact 
colour mapping used when fading. In addition, the RwindowTreeNode functions have variants which allow these default 
parameters to be over-ridden when they are called. 

Parameters 

TUints aBiackMap Black map fading parameter. 
Tuints awhiteMap White map fading parameter. 

See a£so: 

SetDefaultSystemPointerDjirsor { ) 

void SetDefaultSystemPointerCursor (Tint aCursorNumber) ; 

Support 

Supported from 6.0 

Descriptors 

Sets the default system pointer cursor. 

This function can only be called by the owner of the system pointer cursor list. By default the 0th entry in the pointer cursor list is 
assigned as the system pointer. The function allows any cursor from the list or even no cursor to be set as the system pointer 
cursor. 

Notes 

• Ownership of the system pointer cursor list can be obtained by calling ciaimSystemPointerCursorList o when no-one else 
has ownership. 

Parameters 

Tint aCursorNuirtoer The index of the new default system pointer cursor within the system cursor list. 
Parisc codes 

If this function is called when this session is not the owner of the system pointer cursor list. 

SetDoiableClick { ) 

void SetDoubleClick (const TIimeIntervalMicroSeconds32 &alnterval, Tint aDistance); 

Description 

Sets the system-wide double click settings. 
Note: 

• Double click distance is measured, in pixels, as the sum of the X distance moved and the Y distance moved between clicks. 
For example: a first click at 10, 20 and a second click at 13,19 gives a distance of (13-1 0)+(2 1-20) = 4. 

Parameters 

const TTimemtervaiMicroSeconds32& aintervai Maximum interval between clicks that constitutes a double click 
Tint aDistance Maximum distance between clicks that constitutes a double click 

See aSso; 



SetHotKey {) 
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Tint SetHotKey (THotKey aType, TUint aKeyCode, TUint aModifierMask, TUint aModifier); 

Description 
Sets hot keys. 

Hotkeys allow standard functions to be performed by application-defined key combinations. 

This function maps any key press (with optional modifiers) to one of the hot keys defined in THotKey. More than one key 
combination may be mapped to each hot key: a new mapping is added each time the function is called. 

Modifier key states are defined in TEventModitier. The modifiers that you want to be in a particular state should be specified in 
aModifierMask and the ones of these you want to be set should be specified in aModifiers. For example, if you want to capture 
FN-A and you want the SHIFT modifier unset, but you don't care about the state of the other modifiers then set both the flags for 

SHIFT and FN in aModiferMask and Only Set FN in aModifiers. 

Note: 

• Default hotkey settings exist, but this function can be used for customisation. Typically it might be be used by a shell 
application or other application that controls system-wide settings. 

Parameters 

THotKey aType The hot key to be mapped 

TUint aKeyCode The keycode to be mapped to the hot key 

TUint aModifierMask Modifier keys to test for a match 

TUint aModifier Modifier keys to be tested for "on" state 

Return vaSue 

TInt KErrNone value if successful, otherwise another of the system-wide error codes. 



SetKeyboardRepeatRate {) 

void SetKeyboardRepeatRate (const TTimeIntervalMicroSeconds32 & alnitialTime, const TTimeIntervalMicroSeconds32 & aTime); 

Description 

Sets the system-wide keyboard repeat rate. 

This is the rate at which keyboard events are generated when a key is held down. 
Note: 

• The default settings for the keyboard repeat rate are 0.3 seconds for the initial delay, and 0.1 seconds for the interval 

between subsequent repeats. However, since the settings are system-wide, these will not necessarily be the current settings 
when an application is launched: the settings may have been over-ridden by another module. 

Parameters 

const TTimeIntervalMicroSeconds32& alnitialTime 
const TTimeIntervalMicroSeconds32& aTime 

See aSso: 

SetModif ierSt.at.es () 

void SetModif ierState (TEventModif ier aModifier , TModifier State aState) ; 

Sets the state of the modifier keys. 

This function is typically used for permanent modifier states such as Caps Lock or Num Lock, but other possible uses include on- 
screen function key simulation, or the implementation of a Shift Lock key. 



Time before first repeat key event 

Time between subsequent repeat key events 
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Parameters 

TEventModif ier aModif ier Modifier to Set. 
TMociifier State aState Modifier State. 

See also: 

m fA9.VJ?l9. Qif ier _S t ace _( )_ 

SetPointerCursorArea ( ) 

void SetPointerCursorArea (const TRect& aArea) ; 

Support 

Supported from 6.0 

Description 

Sets the area of the screen in which the virtual cursor can be used while in relative mouse mode, for the first screen display mode. 

This function sets the area for the first screen mode — the one with index 0 — which in most devices will be the only screen mode. 
The following function overload can be used to set the screen area for other modes. The area is set and stored independently on 
each screen mode, so that it is not necessary to call this function again when switching back to the first screen mode. 

The default area is the full digitiser area. When you set the area it will come into immediate affect, i.e., if necessary the current 
pointer position will be updated to be within the new area. 

Notes: 

• Relative mouse mode is where the events received from the base by window server are deltas from the last position of the 
pointer, as opposed to absolute co-ordinates. 

• This function is honoured even if there is a mouse or pen (e.g. on the emulator), by mapping the co-ordinates of where you 
click into the area set using this function. However the function does not restrict clicks outside of the 'drawing area' on the 
Emulator, to allow you to select items on the fascia. 

Parameters 

const TRect& aArea The area of the screen in which the virtual cursor can be used. 

SetPointerCursorlrea ( ) 

void SetPointerCursorArea (Tint aScreenSizeMode, const TRect& aArea) ; 

Support 

Supported from 6.0 
Description 

Sets the area of the screen in which the virtual cursor can be used while in relative mouse mode, for a specified screen display 
mode. 

The default area is the full digitiser area for the given mode. When you set the area it will come into immediate affect, i.e., if 
necessary the current pointer position will be updated to be within the new area. 

The area is set and stored independently on each screen mode, so that it is not necessary to call this function again when 
switching back to a mode. 

Notes: 

• Relative mouse mode is where the events received from the base by window server are deltas from the last position of the 
pointer, as opposed to absolute co-ordinates. 

• The previous function overload may be used to set the screen area for only the first mode. 

• This function is honoured even if there is a mouse or pen (e.g. on the emulator), by mapping the co-ordinates of where you 
click into the area set using this function. However the function does not restrict clicks outside of the 'drawing area' on the 
Emulator, to allow you to select items on the fascia. 

Parameters 
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TInt The screen mode to which the new area applies. 

aScreenSizeMode 

const TRect& aArea The area of the screen, in the aScreenSizeMode screen mode, within which the virtual cursor can be 
used. 

Se t?oi n terCur s orMode {) 

void SetPointerCursorMode (TPointerCursorMode aMode) ; 

Support 

Supported from 6.0 
Description 

Sets the current mode for the pointer cursor. 

The mode determines which sprite is used for the pointer cursor at any point. See TPointerCursorMode for more information. 
Parameters 

TPointerCursorMode aMode The new mode for the pointer cursor. 
See aSso: 

. T Po j.n t er C ur so rJMode 



SetPointerCurscrFositicn ( ) 



void SetPointerCursorPosition (const TPoint& aPosition); 



Support 

Supported from 6.0 

DescrSpiiori 

Sets the pointer cursor position. 

This function allows an application to move the virtual cursor. It works in all modes — not just relative mouse mode. 
Note: 

• The function works in screen co-ordinates and honours the pointer cursor area exactly as pen presses do — i.e. only when 
they are in the drawing area on the Emulator. 

Parameters 



const TPoint& aPosition The new pointer cursor position. 



Se tRaracvaRey Code ( ) 



void SetRemoveKeyCode (TBool aRemove) ; 



Support 

Supported from 5.1 

DescrSplsori 

Sets whether to remove the top 16 bits of keypress code — Emulator builds only. 

This function allows the Emulator to use Windows to translate keypresses into the correct key code for each locale, rather than 
having to do the translation for each international keyboard itself. 

The top 16 bits of a keypress code contains the keycode that Windows would produce if the key had been pressed in a typical 
Windows program. If aRemove is EFaise the client can get these top 16 bits — if the value is non-zero the CKeyTransiator uses it 
rather than calculating it's own value. If aRemove is ETrue the window server strips the top 16 bits of the scan code before passing 
the value on to the client. 
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Note: 

• This function is intended for JAVA but it will be useful to any client who creates their own CKeyTransiator and processes 
keyups and downs. 

Parameters 

tbooi aRemove ETrue to remove the code (default), EFaise to pass it to the client. 

SetShadowVector { ) 

void SetShadowVector (const TPoint& aVector) ; 

Description 

Sets the shadow vector. 
Parameters 

const TPoint& aVector New shadow vector 

SetSyst.exr-PointerCursor { ) 

Tint SetSystemPointerCursor (const RWsPointerCursor & aPointerCursor , Tint aCursorNumber) ; 

Descriptor* 

Sets a cursor in the system pointer cursor list. 

To gain access to the list, the client must first call ciaimSystemPointerCursorList o . 
Parameters 

const RWsPointerCursor& aPointerCursor Pointer Cursor to Set in the list 

Tint aCursorNumber Cursor number in the list 

Return vaBtae 

TInt KErrNone if successful, otherwise another of the system-wide error codes. 

SetWindowGroupOrdinalPosition ( ) 

Tint SetWindowGroupOrdinalPosition (Tint aldentifier, Tint aPosition); 

Description 

Sets the ordinal position of a window group. 

This function allows the caller to change the ordinal position of an existing window group. It would typically be used by a shell 
application. 

Parameters 

Tint aldentifier The window group 

Tint aPosition Ordinal position for the window group 

Return vakse 

Tint KErrNone if successful, otherwise another of the system-wide error codes. 

ShsdowVector ( ) 

TPoint ShadowVector ( ) const; 
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Description 

Gets the current value of the shadow vector. 
Return vafiue 

TPoint Current shadow vector 



Simula teKeyEvent ( ) 

void SimulateKeyEvent (TRawEvent aEvent) ; 

Support 

Withdrawn in 6.0 
Supported from 5.1 

Description 

Sends a simulated raw key event to the window server. 
The function is only used for testing purposes. 
Note: 

• This function differs from RWsSession: :SimuiateRawEvent () in that the keys will not be processed by the translator table thus 
allowing you more control over the key that gets through. It is particular useful for sending key presses that change or toggle 
the backlight or contrast. 

• The function is replaced by an overload with the same name, but taking a TKeyEvent, in version 6.0 
Parameters 

TRawEvent aEvent The raw key event to be sent. 



SimulateKeyEvent ( ) 

void SimulateKeyEvent (TKeyEvent aEvent) ; 

Sajpport 

Supported from 6.0 
Description 

Sends a simulated key event to the window server. 
The function is only used for testing purposes. 
Note: 

• All the members of TKeyEvent are honoured except the iRepeat which is ignored and set to 0 by the key handling code. 

• This function replaces an overload taking a TRawEvent. 
Parameters 

TKeyEvent aEvent The key event to be sent. 

Simul&teRawEvesnt { ) 

void SimulateRawEvent (TRawEvent aEvent) ; 

Descriptors 

Simulates raw events as though they come from the kernel. 

Currently this function is used only for testing purposes. It is possible that it may in future be used by applications. 
Parameters 
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TRawEvent aEvent The raw event. 

WindowGroupList ( ) 

Tint WindowGroupList (CArrayFixFlat<TInt>* aWindowList); 

Description 

Gets a list of identifiers of all window groups in all window server sessions. 
An array buffer must be created to store the resultant list. 

Parameters 

CArrayFixFiat<Tint>* aWindowList List of identifiers of all window groups in server 
Return vaBue 

Tint KErrNone if successful, otherwise another of the system-wide error codes. 

WindowGroupList ( ) 

Tint WindowGroupList (Tint aPriority, CArrayFixFlat<TInt> * aWindowList) ; 

Description 

Lists the number of window groups of a given window group priority running in all window server sessions. 

This function is the same as WindowGroupList o described above, but allows the application to restrict the list of window groups to 
those of a particular window group priority. 

Parameters 

Tint apriority Window group priority 

CArrayFixFlat<TInt> ^aWindowList |_ist Of identifiers Of all window groups in Server Of priority aPriority 

Tint KErrNone if successful, otherwise another of the system-wide error codes. 




Enumerations 



E n U m TCompu teMode 



TComputeMode 

Description 
Compute mode flags. 

When a window group takes focus or loses it, the window server can boost its client's thread or process priority to provide a better 
response to the user. How it alters the priority is determined by the current compute mode of the client. 

See also: 

• Compute^:de^. 
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EPriorityControiDisabied Client priority is permanently set to its current level — it is not altered or set by the windowing 

system if the focus changes. 

Thus if computeMode ( ) is called with this flag when a client is in the foreground, it will subsequently 
have foreground priority even if it is in the background. 

EPriorityControlComputeOn Client process's priority iS always Set tO EPriorityBackground. 

EPriorityControicomputeOff client process's priority is set to EPriorityForeground when the window group takes focus, and 

Set tO EPriorityBackground when it loses fOCUS. 

This is the default behaviour. 



E n U ?Y! T Loggi ngConsmand 

T Lo gg i ngComma nd 

Support 

Supported from 7.0 
Description 

Window server logging commands passed to LogCormand ( ) . 
See also: 

ELoggingEnabie Enables logging. 

ELoggingDisabie Disables logging. 

ELoggingstatusDump |_ogs the current status of all the windows in the tree, even if logging is not currently enabled. 

ELoggingHeapDump |_ogs information about the window server's heap size and usage, even if logging is not currently enabled. 

©2002 Symbian Ltd. ^ 
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